OzTEX User Guide

Version 1.8, February 1995

Andrew Trevorrow 19 Abbott Lane North Adelaide 5006 Australia

E-mail: atrevorr@maths.adelaide.edu.au

OzTEX is a shareware version of TEX for the Macintosh (see OzTEX’s Help menu for details about the shareware fee). This document assumes you know how to use a Macintosh. It also assumes you are familiar with TEX, the typesetting system developed by Donald Knuth at Stanford University. An understanding of PostScript is not essential but would be useful if you have access to a PostScript printer.

OzTEX aims to provide a standard TEX environment for the Macintosh that can easily be extended or customized to suit your particular needs. If you have had experience with TEX on some other computer then the way OzTEX works shouldn’t be too surprising.

Comments, bug reports and suggestions are all welcome, but please note that I only reply to e-mail queries from registered OzTEX users.

Contents

1 Introduction 1

2 Configuration files 2 2.1 The default configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.2 The required syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.3 The parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.3.1 Important folders and files . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.3.2 Previewing colours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3.3 TEX parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3.4 PostScript fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.4 Other configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 A guided tour of OzTEX 5 3.1 Starting OzTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2 Choosing an editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.3 Editing a TEX input file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.4 Running TEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.5 Checking for virtual fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.6 Viewing a DVI file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.6.1 Setting the default view . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.6.2 Paper coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.6.3 Zooming in and out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.6.4 Scrolling around . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.6.5 Checking for errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.6.6 Selecting pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.6.7 Keyboard short cuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.7 Printing a DVI file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.7.1 Non-PostScript printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.7.2 Low-level PostScript printing . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.7.3 Standard PostScript printing . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.8 Positioning pages correctly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.9 Continuing from where you left off . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4 OzTEX’s menus 14 4.1 The File menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.2 The Edit menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.3 The TEX menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.4 The View menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.5 The Config menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.6 The Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5 L^{A}TEX 23 5.1 Using L^{A}TEX 2.09 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6 Building format files 24 6.1 Building big formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 7 Fonts 25

7.1 TFM files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 7.2 Creating new TFM files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 7.3 PK files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 7.4 PostScript fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 7.5 Macintosh screen fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 7.6 Encoding files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 7.7 Virtual fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

8 OzTools 30

9 Transferring TFM/VF/PK/DVI files 30

10 Including graphic files in TEX 31 10.1 Including Macintosh graphic files . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 10.2 Compatibility with other DVI drivers . . . . . . . . . . . . . . . . . . . . . . . . . 34 10.3 Including PostScript files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 10.4 Rotating TEX material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

11 Recovering from errors 36 11.1 Errors when loading a configuration file . . . . . . . . . . . . . . . . . . . . . . . 36 11.2 Errors when loading an encoding file . . . . . . . . . . . . . . . . . . . . . . . . . 36 11.3 Errors when running TEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 11.4 Errors when viewing a DVI file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 11.5 Errors when printing a DVI file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

12 Changing OzTEX’s resources 39

13 OzTEX and Metafont 39 13.1 Setting the Metafont mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

14 OzTEX and Dvips 41 14.1 Why use Dvips? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

15 More information 42

1 Introduction

Assuming you correctly carried out the installation instructions in the Read-Me file supplied with OzTEX, you should have a folder that looks something like this:

Here is a brief description of the various folders:

• The TeX-inputs folder contains a large number of TEX input files stored in various subfolders. TEX looks in these sub-folders if it can’t find a given file in your current folder.

• The TeX-formats folder contains the format files read by TEX and the TeX.pool file read by INITEX. Section 6 describes how to create format files.

• The TeX-fonts folder contains many TEX Font Metric files stored in various sub-folders. These TFM files are required by TEX to carry out typesetting; see section 7.1.

• The VF-files folder contains Virtual Font files; see section 7.7.

• The PS-files folder contains various PostScript files. It also contains encoding files in the Encodings sub-folder; see section 7.6.

• The PK-files folder contains PK font files stored in various sub-folders. The name of each sub-folder indicates the “size” of the PK files kept within it; see section 7.3 for how this size is calculated and for more information about PK files. OzTEX is distributed with a fairly small set of PK files (sufficient to print out the documentation on the most common printers). New PK files at any desired size can be built by ; see section 13.

• The Configs folder contains a number of configuration files. Section 2 discusses how these files can be used to customize OzTEX.

• The Help-files folder contains a number of text files. The information in these files can be displayed by selecting their names from OzTEX’s Help menu.

• The TeX-docs folder contains examples of TEX input files, including nasty.tex which is used in the guided tour of OzTEX. It also contains gentle.tex, the source file for Michael Doob’s A Gentle Introduction to TEX. TEX beginners should find this a useful companion to The TEXbook by Donald Knuth.

• The LaTeX-docs folder contains the source files for this User Guide.

• The BBEdit Lite folder contains the BBEdit Lite application and its documentation. BBEdit Lite is a text editor by Rich Siegel which can be used to create and modify TEX input files. If you prefer to use a different text editor then throw away the BBEdit Lite folder.

• The Dvips folder contains Tom Kiffe’s implementation of dvips; see section 14.

• The Metafont folder contains Tom Kiffe’s implementation of ; see section 13.

Please note that Tom’s programs are distributed with OzTEX under a separate shareware fee; see the Read-Me file for details. System 7 or later is needed to run these programs.

2 Configuration files

2.1 The default configuration file

OzTEX reads a configuration file called Default when starting up. This file is kept in the Configs folder along with other configuration files. A configuration file is a simple text file which you can edit and change various parameters that control OzTEX’s behaviour.

Before modifying the Default config file it would be a good idea to save a copy first. Another good idea is to flag your changes with some sort of unique comment so that they can be reproduced easily if and when a new version of OzTEX is released.

2.2 The required syntax

Follow these rules when editing a configuration file:

• Lines starting with “%” are ignored and can be used to include comments. This is also true for lines starting with “@”, but in this case the rest of the line appears in the OzTEX window. All other lines are said to be “significant”.

• Each significant line must contain at least one “=” character. Any characters before the first “=” are ignored, as are spaces or tabs immediately after it. The rest of the line contains the information used by OzTEX, usually in the form of one or more strings. If only one string is required then any further information is ignored. Use double quotes around a string that includes one or more spaces.

• Do not change the order of significant lines (except between the first and last “==”). OzTEX expects to find all the parameters in a fixed sequence.

• To avoid long significant lines you can use “|” to split lines anywhere you like. Upon reading a “|”, OzTEX will ignore the rest of the current line and continue reading from the next line. The best place to use “|” is where a space is allowed; that way you can safely indent the next line to make the file more readable.

• To help keep non-default configuration files short and simple, use these special characters:

1. If “?” is the first character of a parameter’s value then the parameter is not changed and the rest of the line is ignored.

2. “!” is similar to “?” but in addition all remaining parameters are left unchanged (in fact the rest of the file is ignored).

Note that these characters are not recognized as special in the Default file because every parameter must be given a default value, even if empty.

2.3 The parameters

This section discusses all the parameters in a configuration file, in the order required by OzTEX. It would be a good idea to look at the Default config file while reading the following information.

The list of config files appear as items at the end of the Config menu and must correspond to text files stored in the Configs folder. This list is ignored in non-default configuration files.

The list of format files appear as items at the end of the TEX menu and must correspond to the names of .fmt files in the TeX-formats folder. The format file names must not contain any spaces. Place your preferred format first.

The list of help files appear as items in the Help menu and must correspond to text files in the Help-files folder. The Help menu will not appear if the list is empty.

NOTE: Any string starting with “-” in the above three lists will result in a disabled line in the corresponding menu.

The printer resolution (in dots per inch) is used when printing a DVI file and the viewing resolution is used when viewing a DVI file. In both cases the maximum value is 3000 and the minimum value is the resolution of your screen (typically 72). Both resolution values are followed by a string specifying the mode that will be used by when making missing PK fonts; see section 13.1.

The units parameter tells OzTEX how to display dimensions when printing or viewing a DVI file. The normal TEX units are available (in, cm, mm, pc, pt, bp) as well as px (see section 3.6.2).

The paper width and height dimensions are used to detect page-off-paper errors when viewing a DVI file and during low-level PostScript printing. (In standard PostScript printing and non-PostScript printing, OzTEX uses the paper size and orientation selected in the “Page Setup” dialog.) If the width is greater than the height then OzTEX will print or view in landscape mode. The Default values specify A4 paper in portrait mode. If you use US Letter paper then see the US Letter config file for suitable default values.

The horizontal and vertical offsets affect the positioning of all pages when printing a DVI file. They should only be changed if your printer has problems positioning the TEX origin (see page 2 in nasty.dvi). These offsets are not used when viewing a DVI file.

The “show statistics” and other flag parameters specify the initial settings of some check boxes used in the dialogs for printing a DVI file.

2.3.1 Important folders and files

OzTEX needs to know the names and locations of various folders and files. These are specified by path names. A path name can be a simple file name, or it can be a sequence of names separated by colons that represent a valid location in your folder hierarchy. If the path name ends with a colon then it specifies a folder, otherwise a file. OzTEX will generate a warning message if a given path name does not specify a known folder or file. Note that under System 7, OzTEX supports aliased files but not aliased folders.

Partial path names begin with a colon. The first folder in such a path is assumed to be in the same location as the OzTEX application. This is the best way to specify folders and files because then you can move the entire OzTEX folder anywhere you like without having to change any path names.

Full path names begin with the name of a disk; e.g., HD:OzTeX:Help-files:. Path names must be enclosed in double quotes if they contain any spaces; e.g., ":My help:".

OzTEX can be told to search in more than one folder for TEX input files, TFM files, PK files, PS files and VF files. The corresponding parameters also allow “*” at the end of a path name to tell OzTEX to include all sub-folders of the given folder in the search path. OzTEX does not automatically include sub-folders within sub-folders.

2.3.2 Previewing colours

A number of elements can be coloured when previewing a DVI file; they are the paper edges, \special markers and missing fonts. The allowed colours are black, red, green, blue, cyan, magenta, yellow and white (white can be used to make something invisible). On black and white monitors all non-white colours appear black.

2.3.3 TEX parameters

The TEX parameters determine how much memory is allocated for various arrays used by TEX and INITEX. Note that mem_max is temporarily set to mem_top whenever you run INITEX.

Comments in the Default file indicate the possible range of values for each parameter. The Default values are suitable for small to medium-size TEX documents. If you decide to increase one or more of these parameters then you may need to increase OzTEX’s application memory size (via “Get Info” in the Finder’s File menu). Note that a change to mem_top, hash_size, hash_prime or hyf_size will require rebuilding all format files; see section 6.

2.3.4 PostScript fonts

The lines between the first and last “==” tell OzTEX which TFM files are for PostScript fonts (or more accurately, non-PK fonts). The ordering of lines doesn’t matter; they are used by OzTEX to build a list of PostScript fonts. In a non-default config file the first “==” can be replaced by “=+”; this tells OzTEX to add the given fonts to the current list rather than delete the current list and build a new one.

Each line specifies a TFM name, a printer font name, an optional download file, a screen font name, an encoding entry and an optional style. Note that most of the lines in the Default file contain “raw” TFMs for corresponding virtual fonts; see section 7.7.

If a DVI file uses PostScript fonts, the TFM names get converted into printer font names when printing the file on a PostScript printer. OzTEX allows non-resident PostScript fonts to be downloaded on demand. The Utopia lines at the end of the Default file have an extra string (starting with “<”) after the printer font name. This specifies the file to be downloaded if the corresponding font is used; see section 7.4 for more information.

The screen font names are used when viewing a DVI file with PostScript fonts, and when printing the file on a non-PostScript printer. If you are unsure about which screen font would best match a particular PostScript font, you must still specify something (such as “?”). If OzTEX can’t find a specified screen font it will warn you and use the system font instead. To obtain the best results when viewing or printing a DVI file with PostScript fonts you must get the matching screen fonts.

Each screen font can appear in a certain style defined by a set of flags: “b” for bold, “i” for italic, “u” for underline, “o” for outline, “s” for shadow, “c” for condense and “e” for extend. If the style is not specified then OzTEX uses the font’s plain style.

An encoding entry is the name of a user-defined encoding file (or “nil” if the TFM file and screen font use the same encoding). Section 7.6 discusses encoding files.

2.4 Other configuration files

OzTEX’s Config menu lets you switch rapidly from one configuration file to another. This is especially useful if you have access to more than one printer because each printer will probably require a separate configuration file. There are many other uses for configuration files; see section 4.5 for a brief description of the various config files supplied with OzTEX. It is a simple matter to create your own files and add their names to the list in the Default file.

3 A guided tour of OzTEX

The aim of this section is to get you acquainted with OzTEX’s major features.

3.1 Starting OzTEX

Assuming you’ve installed everything, double-click on the OzTEX application file to get the program started. After a brief pause you should see a window with the title “OzTEX” and a couple of messages showing the current version of OzTEX and the path name of the Default configuration file just loaded. The Default file’s list of PostScript fonts contains references to an encoding file, so it will also be loaded.

If you made a mistake during installation, or when editing the Default file, then you might also get one or more error messages. The messages should give you some idea of how to fix the problem.

The OzTEX window is always present; note that it has no close box in the top left corner. This window provides a terminal-like interface for OzTEX. It cannot be edited, but you can copy its contents to the Clipboard or save it to a text file.

You can also start up OzTEX by double-clicking on any OzTEX-created file ending in .xxx; e.g., foo.log or foo.dvi. The advantage of this start up method is that foo.tex will appear in the TEX menu and foo.dvi will appear in the Print and View menus. Also, if foo.log exists and contains a known format then OzTEX will automatically make this the current format so you can immediately typeset foo.tex by hitting Command-T. If foo.tex can’t be found then OzTEX will look for foo.ltx (this is a popular file naming scheme used to distinguish L^{A}TEX input files). Under System 7, you can drag-and-drop foo.tex or foo.ltx onto the OzTEX icon and OzTEX will immediately typeset the file.

The production of a TEX document typically involves a number of iterations through the following cycle: edit, typeset, preview and print. (People concerned about our dwindling forests will hopefully preview many more times than they print.) Let’s go through this cycle step by step.

3.2 Choosing an editor

OzTEX does not have an integrated text editor, but if you are using System 7 or later you won’t find this too much of a problem. After installing OzTEX and starting it up for the very first time, select “Choose Editor” from the Edit menu and use the standard file dialog to locate and select the application you’ll be using to edit your TEX/L^{A}TEX input files. If the chosen application supports Apple events then OzTEX remembers its name and location for use in all future OzTEX sessions (or until you choose another editor).

Having chosen an editor, OzTEX will use it as the target of an “open file” event sent when you select “Edit foo.tex” from the Edit menu. This item always shows the name of the most recently typeset file. See section 4.2 for more details about the items in the Edit menu.

3.3 Editing a TEX input file

A TEX input file is a standard Macintosh text file. We won’t create an input file from scratch, instead we’ll use one of the sample files provided in the TeX-docs folder. There is nothing special about this folder, or LaTeX-docs. I simply like to keep my TEX and L^{A}TEX input files in separate folders. You can keep your input files anywhere you like.

The file we’ll use is called nasty.tex. As the name suggests, it is not a typical TEX input file, but it does illustrate most of the things you’ll encounter when using OzTEX in the future.

Switch to your text editor and open nasty.tex from the TeX-docs folder. The only change we’ll make to nasty.tex is to add a deliberate error: insert the illegal command \xxx at the start of the file. Save this change before switching back to OzTEX.

3.4 Running TEX

Let’s now typeset nasty.tex. Before starting TEX we need to make sure that the correct format will be used. (This check is not normally needed if the log file exists and “Use Format in Log” is ticked. However, when typesetting a file for the very first time it is best to manually set the correct format.) All the available formats appear at the end of the TEX menu. Check this menu and make sure the Plain format is ticked; this is the format required by nasty.tex.

Choose “TEX … ” from the TEX menu and open nasty.tex. The OzTEX window will be cleared, TEX will start up, load the Plain format, and begin reading the given input file.

When it sees the unknown command, TEX will display a suitable error message, beep, and wait for you to type something. Note that a solid block cursor sits next to TEX’s “?” prompt. This block cursor always appears when TEX is waiting for you to type something. The OzTEX window should contain the following:

   This is TeX, Version 3.1415 (no format preloaded)
   **&Plain nasty.tex
   (nasty.tex
   ! Undefined control sequence.
   l.5 \xxx
   ?

Chapter 6 in The TEXbook explains what you can do in such a situation. (Section 4.2 describes how you can type “e” to tell OzTEX to switch to your editor and open the file containing the error, possibly with the error line selected.) In this case we can simply ignore the error and continue by hitting the Return key. Although nasty.tex is not very nice, you shouldn’t see any more TEX errors. A 19-page DVI file called nasty.dvi should be created.

Have a look at the second item in both the File and View menus. Whenever a new DVI file is created, its name will automatically appear in these items so you can quickly print or view the DVI file without going through the standard file dialog. The second item in the TEX menu has also been updated with the name of the most recent input file (nasty.tex in this case), so you can easily typeset the same file again by pressing Command-T. The file name also appears in the bottom item of the Edit menu so you can quickly switch back to your editor by pressing Command-E.

OzTEX supports background typesetting. At any time while TEX is running you can switch to another application and TEX will continue to run in the background. Whenever OzTEX finishes a lengthy task in the background (like typesetting or printing), or if some sort of user interaction is required (say a TEX error occurs), then under System 6 or later you will be notified by a flashing OzTEX icon in the menu bar. A diamond mark will also appear next to OzTEX in the list of current applications.

3.5 Checking for virtual fonts

Before proceeding to view or print a DVI file created for the first time, it is a good idea to check and see if any virtual fonts are used (section 7.7 has more information about virtual fonts). Select “Fix VFs in DVI” from the TEX menu and open nasty.dvi. OzTEX lists all the fonts used in the DVI file and prefixes each font with its type:

PK indicates a packed pixel font (see section 7.3);

PS indicates a PostScript font (see section 7.4);

VF indicates a virtual font.

As it happens, nasty.dvi does use a couple of virtual fonts, so OzTEX processes every page, fixes all virtual font references and creates a new version of nasty.dvi.

If your documents use virtual fonts, it is advisable to tick “Fix VFs after TEX” in the TEX menu; then you don’t have to remember to run “Fix VFs in DVI” before viewing or printing a DVI file.

3.6 Viewing a DVI file

The next step is to preview the DVI file and check for problems that TEX may have missed, like missing fonts, bad page breaks, spelling mistakes, etc. Let’s have a look at nasty.dvi by choosing the second item in the View menu. OzTEX creates a new window, called the “view” window, and sets its title to the selected DVI file. A dialog box has also appeared:

The scroll bar allows you to select any page in the DVI file. There are also two edit boxes in which you can type a DVI page number or TEX page number. (The dialog box also allows you to change some other options, but we’ll ignore them at this stage; see the description of “View DVI … ” on page 18 for details.) Play around with the scroll bar if you like but make sure the 2nd DVI page is selected before proceeding. To view this page simply click in the View button or hit the Return key.

The 2nd page in nasty.dvi contains a single rule with some text below it. Dotted lines representing the paper edges should also be visible. Now is a good time to adjust the size and location of the OzTEX and view windows to suit your screen. When you quit, OzTEX will remember the current window settings and use them the next time it starts up.

3.6.1 Setting the default view

OzTEX displays the top left corner of the paper at a scale approximating the document’s actual size (see below for more about scaling). This is the initial default view, but it might not suit the size or dimensions of your particular monitor. To change the default view, you just set up the desired scale and/or location using the various commands described below and then select “Save as Default View” from the View menu. OzTEX remembers your new default view until you decide to change it.

To restore the initial default view, simply select “Actual Size” from the View menu, move the scroll bar thumb boxes up and to the left as far as possible, then select “Save as Default View”.

3.6.2 Paper coordinates

An understanding of the coordinate system used by OzTEX to view (and print) a DVI page would be useful. The px units mentioned earlier are “paper pixels”; they are OzTEX’s internal units. The resolution parameters in a configuration file define the number of paper pixels per inch; one parameter is only used when printing a DVI file and the other is only used when viewing a DVI file.

OzTEX uses a coordinate scheme in which the paper pixel at (0,0) is exactly one inch in from the top and left edges of the paper. This position is referred to as the “TEX origin” because it is also the origin of the coordinate system used in DVI files. Every character, rule or \special has a specific location defined by a pair of paper pixels (h,v). Vertical coordinates increase down the paper and horizontal coordinates increase to the right.

If the view window is frontmost then the cursor is changed to a cross whenever it moves over the contents region. The current position of the cross is shown (in paper coordinates) in a box at the lower left corner of the view window. You can click in this box to change units.

3.6.3 Zooming in and out

A “scale factor” is used to display a DVI page at a particular size. It defines the number of paper pixels in each Macintosh screen pixel (both horizontally and vertically) and always has an integer value greater than or equal to 1. Certain View menu items change the current scale factor:

• “Full View” sets the scale factor to its maximum value and displays the entire page and paper edges in the middle of the view window.

• “Actual Size” sets the scale factor so that the new view will show the page at roughly the right size (it’s only approximate because the scale factor is an integer value).

• “Zoom In” halves the current scale factor.

• “Zoom Out” doubles the current scale factor.

You can also change the scale factor by clicking in the view window in a variety of ways:

• Click-and-drag within the viewing area to zoom in to the selected rectangle. If you want to cancel the operation then make the rectangle very thin (not small, because that might be interpreted as a simple click).

• A simple click will zoom in by halving the scale factor.

• Command-click will zoom in by decrementing the scale factor.

• Option-click will zoom out by incrementing the scale factor.

• Shift-click will zoom out by doubling the scale factor.

• Option-Command-click will temporarily magnify a small area under the cursor until the mouse button is released. The scale factor in the magnified area is 1.

• A beep occurs if you can’t zoom in or out any further.

When you zoom in or out by clicking, OzTEX will try to make the point you clicked the middle of the new view. However, when you choose a menu item, OzTEX tries to keep the top left page location fixed. In both cases it is possible that the view may unexpectedly shift so that it remains within the scrolling limits set by OzTEX. Experiment with the various ways of zooming to see which methods you prefer.

The most precise display occurs when the scale factor is 1 because each screen pixel corresponds to exactly one paper pixel. OzTEX doesn’t allow you to zoom in any further than this.

3.6.4 Scrolling around

The view window has scroll bars that allow you to move over the page in the standard Macintosh manner. Note that the arrow keys can be used instead of clicking in the scroll arrows. OzTEX won’t let you get too far away from the page/paper boundaries. If you do manage to get lost just choose “Full View”.

3.6.5 Checking for errors

It is a good idea to select the “Page Info” item at least once while viewing a DVI file. This item displays its results in the OzTEX window. The display includes a list of all the fonts used in the DVI file and clearly indicates any that are missing. It also lists any \special commands on the current page, showing their locations and arguments.

3.6.6 Selecting pages

There are a number of interesting pages in nasty.dvi. Use “Previous Page”, “Next Page” or “Go to Page … ” to have a look at some of them. Note that the current DVI/TEX page numbers are always displayed in the view window’s title bar. Here are some points of interest:

• The current scale factor and page location will only change if the selected page is off the paper, in which case OzTEX will beep and display a full view. Pages 13 to 15 illustrate this behaviour. When you move from such a page to a normal page, OzTEX switches back to the default view.

• OzTEX may take a little while to interpret and display a selected page, depending on how complicated it is. Hit Command-C or Command-Dot if you get bored.

• The view window is updated in the following manner. Visible paper edges are drawn first, then \special bitmaps and markers, then rules, then characters on a font by font basis, starting with the font that has the least number of characters on the page. Try a full view of page 19.

• Page 3 has examples of \special commands. OzTEX is able to preview included files of type PICT, PNTG or EPSF; see section 10 for more information. The location of each \special is indicated by a small marker. Note that the size of this marker does not change as you zoom in or out.

• Page 9 uses a couple of PostScript fonts; see section 7.4.

• All the fonts used on page 12 are deliberately missing.

• Page 16 has examples of bad \special commands.

When you have finished previewing the DVI file just click in the view window’s close box. The view window is also closed automatically when you run TEX, print a DVI file or load a configuration file.

3.6.7 Keyboard short cuts

OzTEX provides a number of keyboard short cuts to make it easier to proofread a DVI file:

• Type “g” to go to a given page and switch to the default view.

• Type “f” to move to the first page. The current scale and location do not change.

• Type “l” to move to the last page. The current scale and location do not change.

• Type “n” to move to the top of the next page without changing the current scale or horizontal position.

• Type “b” to move to the bottom of the previous page without changing the current scale or horizontal position.

• Hit the space bar to scroll forwards through a document.

• Hit the Delete key to scroll backwards.

• Hit the Return key to bring either the view window or the OzTEX window to the front.

• Type “w” to close the view window.

• Type “o” to bypass the view dialog and open the most recently viewed DVI page (or page 1 if you haven’t viewed anything yet). OzTEX will also restore the scale factor and location you last used.

Note that if the page selected by any of the above short cuts is off the paper then OzTEX will beep and switch to a full view.

3.7 Printing a DVI file

Before printing a DVI file it is a good idea to select “Page Setup” from the File menu and make sure the paper size and orientation are correct. To print nasty.dvi choose either of the top two items in the File menu. Choosing the second item simply avoids the standard file dialog.

OzTEX tries to support all Macintosh printers, but it also tries to take advantage of the sophisticated features available in PostScript printers. This has often meant going against Apple’s guidelines for device-independent printing, so OzTEX’s printing code has had a long and interesting history! All this is half-explanation and half-apology for what might seem to be an unnecessarily complicated printing strategy.

OzTEX supports four(!) methods of printing a DVI file:

1. Non-PostScript printing.

2. Low-level PostScript printing.

3. Standard PostScript printing.

4. Using dvips.

Of course, most people will only ever use one or two of these methods. The printing method chosen by OzTEX depends on whether or not the current printer (selected in the Chooser) is a PostScript device, and the current state of two flags in the File menu: “Use Standard PostScript” and “Use DVIPS”.

If “Use DVIPS” is ticked then OzTEX ignores both the current printer and the “Use Standard PostScript” flag. Instead, it will call dvips to translate the DVI file into a PostScript file, as described in section 14. If “Use DVIPS” is not ticked then one of the following three printing methods will be selected.

3.7.1 Non-PostScript printing

If the current printer is not a PostScript device then the “Use Standard PostScript” flag is ignored. OzTEX will open the DVI file and display a printer-specific dialog. (If the printer resolution parameter does not match the actual resolution of the current printer then you’ll first be warned about possible scaling problems; see page 39.) For example, if the current printer is a StyleWriter then you’ll get a dialog like this:

The dialog box lets you change various options specific to the current printer. OzTEX adds some extra items at the bottom of the dialog:

• Some text showing the first and last DVI/TEX pages. This information can be useful when entering DVI page numbers in the “From” and “To” edit boxes.

• Edit boxes for changing the page increment and DVI magnification.

• Check boxes for reversing the page order, showing statistics and making missing PK fonts.

Click on the Print button or hit the Return key to start printing. At any time while OzTEX is printing you can switch to another application and OzTEX will continue to print in the background.

3.7.2 Low-level PostScript printing

If the current printer is a PostScript device and “Use Standard PostScript” is not ticked then OzTEX will open the DVI file and display the following dialog:

This dialog box lets you change a variety of print options. Most of them should be fairly obvious; details can be found in the description of “Print DVI … ” on page 14. The option you’ll most often want to change is the page range. The two scroll bars control the first and final pages. OzTEX prevents you from choosing a first page greater than the final page. Play around with the scroll bars but restore their values so that every page will be printed. Click in the Print button or hit Return to start printing.

If the printer is found then a status box will appear and keep you up-to-date on your job’s progress and the state of the printer. As each page is translated into PostScript its DVI/TEX page numbers are displayed in the OzTEX window.

You can’t actually print every page in nasty.dvi because there is a deliberate error that makes this impossible. The first 11 pages should not cause any problems (assuming you’re using A4 paper) but the rest will generate nearly every type of error message you’re ever likely to encounter. You should eventually get up to page 17 where a deliberate PostScript error in a \special file will prevent any further pages being printed. (OzTEX may start translating page 18 before the error is seen.)

The above dialog box also lets you send the PostScript output to a file instead of the printer. This file is an ordinary text file with a default name of nasty.ps. A warning: the PostScript code generated by OzTEX is resolution-dependent. If you send this code to a PostScript device with a resolution different to that of the current printer resolution parameter then the output might look a little strange.

A note for PostScript hackers: OzTEX begins the PostScript output by copying the contents of a file called DVItoPS.pro (kept in the PS-files folder). OzTEX will also look for a file called global.ps in the current folder and, if found, include its contents at the end of DVItoPS.pro. For example, global.ps in the PS-files folder shows how you can get the word “DRAFT” printed in the background on every page.

3.7.3 Standard PostScript printing

If the current printer is a PostScript device and “Use Standard PostScript” is ticked then OzTEX will open the DVI file and display the standard dialog for that printer:

Below the normal options for the current printer, OzTEX adds some extra items (the same ones described under the dialog box for non-PostScript printing on page 11). Click on the Print button or hit the Return key to start printing.

PostScript hackers should note that when standard PostScript printing is used to print a DVI file, OzTEX does not use DVItoPS.pro; instead it uses a file called OzTeXdict.pro (also kept in the PS-files folder). The PostScript code in OzTeXdict.pro is very similar to DVItoPS.pro, but there are some subtle differences. I decided it would be unsafe to allow inclusion of a global.ps file when using standard PostScript, but I have allowed for similar tricks by making OzTEX look for OzTeXdict.pro in the current folder before looking in the PS folder(s).

Although there are significant advantages to using standard PostScript, there are some disadvantages. There is a limitation in LaserWriter print drivers older than version 8 that causes a PostScript error when printing all but the simplest of DVI files. OzTEX is able to predict when this error is likely to occur and will display a suitable warning message. Also, standard PostScript code takes longer to print and saved PostScript files are a little bit larger. If you want to use OzTEX’s more efficient low-level printing code then leave “Use Standard PostScript” unticked. Another advantage of low-level PostScript printing is that any PostScript error messages will appear in the OzTEX window (although on some printers, like the LaserWriter Select 310, you might need to send geterrors.ps first).

In standard PostScript printing, OzTEX has to go through all selected DVI pages first and determine font and character usage. All the PK character bitmaps used in the document are then downloaded at the beginning, so the first page in a long document might take some time to be printed.

3.8 Positioning pages correctly

For your DVI output to appear in precisely the right location on the paper, the TEX origin must be exactly one inch in from the top and left paper edges. Page 2 in nasty.dvi contains a thick rule with its top left corner exactly at the TEX origin. If the printed page shows a significant discrepancy then adjust the horizontal and vertical offsets in the Default configuration file to shift the origin to the correct position.

Note that if your printer is set up for US Letter paper then before adjusting the offsets you should first change the Default file’s paper width to 8.5in and the paper height to 11in.

If you use more than one printer then you will probably need a separate configuration file for each printer. You might also need to create a separate configuration file for landscape printing.

3.9 Continuing from where you left off

That’s the end of the guided tour. One more useful feature to note is that when you quit, OzTEX remembers the TEX file, the format, the DVI file, and the most recently previewed DVI page, including the scale and location for use by the “o” keyboard short cut. The next time OzTEX starts up it will recall all this information so you can continue working from where you left off. (Double-clicking on a file to start up OzTEX will of course override some of this information.)

4 OzTEX’s menus

Let’s go through each menu and discuss each item in detail, concentrating on the things not mentioned in the guided tour.

4.1 The File menu

Print DVI …

Prints a selected DVI file. After selecting the DVI file you’ll be presented with a dialog box that depends on the current printer and the settings of “Use Standard PostScript” and “Use DVIPS” (these flags are described later). The dialog box for low-level PostScript printing (see page 11) lets you change these printing options:

• The page range. The first and final pages are controlled by separate scroll bars; their current values are displayed in the form “DVI page/[TEX page]”.

• The paper orientation (landscape or portrait).

• The page order (reverse or normal).

• Printer memory management (conserve VM or not). VM is PostScript’s “virtual memory” and the output generated by OzTEX can consume an awful lot of it, especially if your document uses a large number of non-PostScript fonts. If you get a “VMerror” when printing a document then try again with the conserve VM option checked. You should only need to do this for a very unusual document, like a font catalog.

• The paper source (manual feed or normal input tray).

• Whether or not to show statistics about font, rule and \special usage.

• Whether or not to make missing PK fonts.

• The number of copies of each page.

• The page increment. The primary purpose of this option is to simplify the printing of a document on both sides of the paper. If the first page is 1 and an increment of 2 is chosen then OzTEX will print pages 1, 3, 5, 7, etc. Depending on how your printer stacks the output, you can then put these pages back into the input tray and print the DVI file again using the same increment but starting from the second DVI page (and reversing the page order; this will not effect which pages are printed but simply changes the order in which they are done).

• The DVI magnification (expressed as an integer 1000 times the desired magnification). You should use the default value unless you know what you’re doing. If the DVI file uses non-PostScript fonts then you should probably stick to the numbers corresponding to TEX’s \magstep values; i.e., 1000, 1095, 1200, 1440, etc. See Chapters 4 and 10 in The TEXbook for details. A document using only PostScript fonts can be printed at almost any magnification (OzTEX allows values from 1 to 10000).

What happens next depends on which dialog button you select. The default Print button will send the PostScript output to the current printer. A status box will appear and indicate what is happening to your job and warn you about any printer problems. Or you might prefer to save the PostScript output to a given text file. Any change to a check box option will be remembered the next time you print a DVI file, unless you decide to Cancel the dialog.

The dialog boxes for standard PostScript printing (see page 12) and non-PostScript printing (see page 11) let you change various options specific to the current printer. OzTEX adds some extra items at the bottom of the dialog so you can change the page increment or DVI magnification, and decide whether or not to reverse the page order, show statistics, or make missing PK fonts.

Regardless of which printing method OzTEX decides to use, the messages displayed in the OzTEX window are almost identical. The DVI/TEX page numbers are displayed as each page is processed. Any error messages or statistics apply to the most recently displayed page numbers (although this is not true for messages sent back by a PostScript printer because these occur asynchronously). At any time you can hit Command-C or Command-Dot to cancel printing, or you can switch to another application and OzTEX will continue to print in the background.

Print ?.dvi

Prints the indicated DVI file. You can print the file even after moving to another folder. This item is initially disabled; the file name changes after you select a DVI file via “Print DVI … ” or “View DVI … ”, or create a DVI file by running TEX.

Print Text …

Prints a selected text file. If OzTEX decides to use low-level PostScript printing then this file is sent after the TEXTtoPS.pro file which is kept in the PS-files folder. If you know a little about PostScript then you might like to modify TEXTtoPS.pro to suit your own needs. For example, the tab width is defined in TEXTtoPS.pro.

If OzTEX uses standard PostScript printing, or non-PostScript printing, then you’ll get a printer-specific dialog with an extra edit box that lets you specify the tab width. The default tab width is 3; this is the value used in various text files supplied with OzTEX. Text files are printed using 10 pt Courier.

Page Setup …

The “Page Setup” dialog lets you select various printer-specific options that will be used in standard PostScript printing or non-PostScript printing. If you select OK then the dialog settings are remembered for later OzTEX sessions. However, if the Chooser is used to select a different printer then the settings will be restored to default values for the new printer.

Note that in low-level PostScript printing, OzTEX ignores the “Page Setup” settings. In this case the paper size is determined by config file parameters.

Use Standard PostScript

Tick this flag if you want to use the standard Mac print dialogs when printing a DVI file or text file to a PostScript printer. (However, if the currently chosen printer is not a PostScript device then OzTEX ignores this flag and switches to non-PostScript printing.)

If “Use Standard PostScript” is ticked, then remember that “Page Setup” must be used to select the paper size and orientation before printing a DVI file or text file. You can also select other handy features like 2-up printing if you have the LaserWriter 8 print driver.

Use DVIPS

This item is only enabled under System 7 or later. Tick this flag if you want OzTEX to call dvips to translate a DVI file into PostScript. The top two items in the File menu change to “DVIPS … ” and “DVIPS foo.dvi” when “Use DVIPS” is ticked. For more information about dvips, see section 14.

If “Use DVIPS” is ticked then OzTEX ignores the “Use Standard PostScript” flag. Of course, “Use DVIPS” is ignored when printing a text file.

Send PostScript …

Sends a selected text file, presumably a PostScript program, to the current printer. (If it isn’t a PostScript printer then you won’t get far!) The PS-files folder contains a number of interesting files that can be sent to any PostScript printer.

If a PostScript file is sent to spooling software rather than directly to the printer then you probably won’t see any messages sent back to the OzTEX window. In such an environment it’s a good idea to send errhandler.ps first so that any PostScript errors will be printed on paper.

Save OzTEX Window …

Saves the contents of the OzTEX window to a given text file. The Default config file sets the file name to Oz.text. This item is disabled if the OzTEX window is empty or not the front window.

Quit

Quits OzTEX.

4.2 The Edit menu

OzTEX does not have an integrated text editor, so the standard items in this menu are normally disabled (although Cut/Copy/Paste/Clear can be used in a dialog box with edit items).

Copy to Clipboard

Copies the contents of the OzTEX window to the Clipboard so you can paste it into a text file. This item is disabled if the OzTEX window is empty or not the front window.

Font

Selects the screen font used to display text in the OzTEX window. You can choose from any of the currently installed fonts, but for best results it is advisable to use a fixed-width font like Monaco or Courier. This item is disabled if the OzTEX window is not the front window.

Size

Selects the point size of the font used in the OzTEX window. (The available sizes are stored in a MENU resource in OzTEX, so use ResEdit if you want to change the supplied values.) This item is disabled if the OzTEX window is not the front window.

Choose Editor …

This item is only enabled under System 7 or later. It lets you select the target application (presumably an editor) to which OzTEX will send “open file” events. If the chosen application can receive such events then OzTEX remembers its name and location for later use (as described below).

Select Error Line

This item is only enabled under System 7 or later. If ticked, this flag tells OzTEX to include an extra parameter in the “open file” event sent when you type “e” in response to TEX’s “?” prompt (which normally occurs after a TEX error). The extra parameter specifies the line number so your editor can automatically select the line containing the error. However, some editors can’t handle the extra parameter and won’t even open the file. You will need to experiment with your editor to see if it can select the error line; if it can’t then make sure “Select Error Line” is not ticked. Note that BBEdit Lite can’t handle the extra parameter but the full version of BBEdit can. Recent versions of Alpha can.

Edit ?.tex

This item is only enabled under System 7 or later. If selected, OzTEX will send an “open file” event to your current editor. OzTEX will launch the editor if necessary. This item normally contains the name of the most recently typeset file (it will always match the file shown in the TEX menu’s 2nd item).

4.3 The TEX menu

TEX …

Typesets a selected input file using the current format (or the format in the corresponding log file if “Use Format in Log” is ticked; see below for more about this item). The OzTEX window acts like a terminal during a TEX session.

One of the nicest things about TEX is that it behaves the same way on a large range of different computer systems. Virtually everything you read in The TEXbook will apply to the version of TEX run by OzTEX (and the same goes for Leslie Lamport’s L^{A}TEX book if you use that format). Only a few special features have been added in OzTEX:

• Most of TEX’s capacity parameters are set at run-time in a configuration file rather than at compile-time. If you get a “TEX capacity exceeded” error then you should be able to overcome the problem by increasing the appropriate parameter (see page 37).

• TEX can be told to look in more than one folder when searching for an input file or TFM file (by setting the appropriate config file parameters).

• You can interrupt a TEX session at any time by typing Command-C or Command-Dot. Depending on what it is currently doing, TEX usually responds immediately with a suitable message and the “?” prompt. If you hit Command-C or Command-Dot at this stage (or whenever the block cursor is visible) then TEX will immediately abort.

• TEX will continue typesetting in the background if you switch to another application.

TEX ?.tex

Typesets the indicated input file using the current format (or the format in the corresponding log file if “Use Format in Log” is ticked). This item remembers the most recently typeset file.

Use Format in Log

If this item is ticked, then before typesetting foo.tex OzTEX will look in foo.log to see which format should be used. (In log files created by OzTEX the format appears after the “&” on line 2.) If the log file exists and the format is known (i.e., exactly matches one of the formats at the bottom of the TEX menu) then OzTEX automatically changes the current format if necessary. If the log file does not exist or does not contain a known format then the current format will be used. The state of “Use Format in Log” is remembered when you quit OzTEX.

Note that if you manage to create a log file with a known but incorrect format then you’ll have to turn off “Use Format in Log” and manually select the correct format before typesetting the corresponding input file.

Fix VFs in DVI …

Selects a DVI file and replaces all virtual font references with appropriate characters and commands from actual fonts. See section 7.7 for more information about virtual fonts.

Fix VFs after TEX

If this item is ticked then OzTEX automatically fixes any virtual fonts in the DVI file created at the end of a TEX run. The state of this flag is remembered when you quit OzTEX.

INITEX

Runs INITEX, a special version of TEX normally used to create format files; see page 24.

List of formats

The items below INITEX are read from the format list specified in the most recently selected configuration file. The Default config file sets the format list to L^{A}TEX and Plain.

The current format is indicated by a tick and will be the one used when you typeset a file (although this will be overridden if “Use Format in Log” is ticked and a log file exists). To change the current format, simply select a different format item. OzTEX automatically ticks the first format found when loading a configuration file, so it’s a good idea to place your preferred format first. Note that if a non-default configuration file uses the “?” character to avoid changing the format list then OzTEX won’t change the current format.

4.4 The View menu

View DVI …

Previews a selected DVI file. OzTEX will open the view window and set its title to the name of the selected DVI file. You’ll then be presented with a dialog box (see page 7) that lets you choose various viewing options:

• The initial page to display. A scroll bar allows you to locate any page in the DVI file. The left and right arrow keys can be used to move the thumb box. You can also type in a specific DVI page or TEX page; if the given number is valid then the other page number is updated and the scroll bar repositioned. If there is only one page in the DVI file then the scroll bar will be inactive.

• The paper orientation (landscape or portrait). Any change to this option will be remembered the next time you view a DVI file, unless you Cancel the dialog. The check box setting will also be used in the dialog for low-level PostScript printing.

• Two more check boxes can be used to tell OzTEX to ignore bad \special commands and/or missing fonts. It is a good idea to select both these check boxes when previewing a DVI file created by another TEX system, otherwise you might get a lot of annoying warning messages. OzTEX remembers these check box settings.

• The last check box can be used to make missing PK fonts (but it will be ignored if “Ignore missing fonts” is selected). OzTEX remembers this check box setting. See section 13 for more details.

• The DVI magnification. You should only alter the default value if you plan to print the DVI file at a different magnification. See the description of “Print DVI … ” in section 4.1 for more details. Note that OzTEX does not remember any change to the DVI magnification.

If you Cancel the dialog then OzTEX will close the view window. If you select the View button then the current DVI/TEX page numbers will be appended to the DVI file name in the view window’s title bar and OzTEX will locate the requested page, interpret it and display it. You might have to wait a moment before seeing anything, especially if it is a complicated page.

OzTEX sets the initial scale factor and page location to values determined by the default view (see section 3.6.1). However, if any part of the page is off the paper then OzTEX will beep and show a full view instead (see the “Full View” item below).

View ?.dvi

Previews the indicated DVI file. Exactly the same sequence of events described above will occur. You can preview the file even after moving to another folder. This item is initially disabled; the file name changes after you select a DVI file via “Print DVI … ” or “View DVI … ”, and after TEX creates a DVI file.

Show OzTEX or Show View

Brings either the OzTEX window or the view window (if open) to the front. The Return key is a keyboard short cut for this menu item.

Page Info

Displays information about the current DVI page in the OzTEX window, bringing it to the front if necessary. This item is disabled if the view window is closed. The information displayed includes:

• The ten TEX page counters stored with the current page (trailing counters with zero values are not shown).

• The total number of pages, viewing resolution, DVI magnification and paper dimensions.

• A list of all the fonts used in the entire DVI file. For each font appearing on the current page OzTEX will show the total number of characters used. Note that the order of fonts may change as you move from page to page; OzTEX sorts the list so that all fonts actually used on the current page appear first. A PostScript font is indicated by its corresponding TFM path name and the requested point size. A PK font is indicated by a PK path name. Missing PK or TFM files are flagged by the message “DOES NOT EXIST”. Missing screen fonts are flagged by the message “NO SCREEN FONT”.

• The number of rules on the page.

• The location and argument of each \special command on the page. The location is expressed in terms of OzTEX’s paper coordinate system; see section 3.6.2. If the \special command includes a valid PICT/PNTG/EPSF file then the width and height of the image’s bounding box is also displayed (if there is an image).

Previous Page

Displays the previous DVI page. This item is disabled if the view window is closed or currently displaying the first page.

Next Page

Displays the next DVI page. This item is disabled if the view window is closed or currently displaying the last page.

Go to Page …

Brings up a dialog box allowing you to select any DVI page for display. This item is disabled if the view window is closed or if the DVI file only has one page.

Full View

Changes the scale factor and location so that the entire DVI page and paper edges are displayed in the middle of the current view window. The scroll bars are disabled and the scale factor is set to its maximum value. This item is disabled if the view window is closed or already displaying a full view.

Actual Size

Changes the scale factor so that the DVI page is displayed as near as possible to its actual size. The top left corner of the view window will still show the same page location, unless shifting is necessary to keep within the scrolling limits. This item is disabled if the view window is closed or already displaying the page at its actual size.

The scale factor is actually set to the nearest integer equal to the viewing resolution divided by the Mac screen resolution. A likely calculation is 300/72 = 4.17, so the scale factor is set to 4. Because of this approximation, a 3 in wide rule in your TEX input file won’t appear exactly 3 in wide in the view window. If this is a serious problem then switch to a configuration file that sets the viewing resolution to some multiple of the screen resolution; you’ll also need a matching set of PK files. Note that 360 = 72 × 5.

Zoom In

Halves the current scale factor. The top left corner of the view window will still show the same page location, unless shifting is necessary to keep within the scrolling limits. This item is disabled if the view window is closed or already displaying the page at minimum scale factor.

Zoom Out

Doubles the current scale factor. The top left corner of the view window will still show the same page location, unless shifting is necessary to keep within the scrolling limits. This item is disabled if the view window is closed or already displaying the page at maximum scale factor.

Save as Default View

Saves the current scale factor and page location as the default view (see section 3.6.1). This item is disabled if the view window is closed.

4.5 The Config menu

Show

Shows the current values of configuration parameters in the OzTEX window. You can choose to show all parameters or just some important subsets. If you select “All” then the output is displayed with the correct syntax for a configuration file; this makes it easy to create a new configuration file by simply saving the OzTEX window.

Load Config …

Lets you select and load a configuration file (not necessarily in the Configs folder) without having to add it to the list of configuration files in the Default file. This means you don’t have to clutter up your Config menu with rarely used config files.

Default

Loads the Default configuration file, resetting all parameters to their default values.

Other configuration files

The remaining items in the Config menu are determined by information given in the Default configuration file. The items must correspond to the names of text files in the Configs folder. Selecting one of these items causes the corresponding configuration file to be loaded. A tick appears next to the most recently loaded file. Here is a brief description of all the non-default config files supplied with OzTEX:

Big TeX — Sets all the TEX parameters to very large values. It also sets the list of formats to Big-L^{A}TEX and Big-Plain. See section 6.1 for more details.

StyleWriter — Configures OzTEX for the StyleWriter printer. The printer and viewing resolutions are set to 360 and both modes to stylewriter. The reverse page order parameter is set to true because this printer stacks pages face up.

ImageWriter — Configures OzTEX for the ImageWriter printer. The printer and viewing resolutions are set to 144 and both modes to imagewriter.

Linotronic — Configures OzTEX for a Linotronic typesetter. The printer resolution is set to 1270 and the mode to linohi. The viewing resolution and mode are not changed.

A5 Portrait — Sets the paper dimensions for A5 paper in portrait mode.

A4 Landscape — Sets the paper dimensions for A4 paper in landscape mode.

US Letter — Sets the paper dimensions for US Letter paper in portrait mode.

View at 144 dpi — Sets the viewing resolution to 144 and the mode to imagewriter. The printer resolution and mode are not changed. Characters from 144 dpi PK files scale better on most Mac screens (normally 72 dpi). Previewing will also be faster and use much less memory.

View CM using PS — Tells OzTEX to preview Computer Modern text fonts using the nearest “equivalent” PostScript screen fonts. If you have the corresponding TrueType or ATM (Adobe Type Manager) fonts, your text will be much more readable, apart from some strange kerning and the odd incorrect character (e.g., you won’t see any “ffi” ligatures). It is important to realise that this is a bit of a hack and you should not try to print documents using this config file, so remember to switch back to the Default config file before printing. The viewing resolution is set to 360 (5 × 72) so that “Actual Size” dimensions will be accurate.

One minor thing to watch out for is that selecting this config file adds a new list of PostScript fonts to the existing list (the list begins with “=+” rather than “==”). No real harm is done if you select the config file more than once; you’ll just be wasting memory. Selecting Default will reset the font list (as will any other config file that uses “==”).

Add CM/PS Fonts — Adds information to the current list of PostScript fonts so that OzTEX can use the CM/PS fonts available from Blue Sky Research. The CM/PS fonts are PostScript versions of the Computer Modern fonts. The screen fonts are available in either ATM or TrueType format and provide a much more readable preview.

Add Lucida Fonts — Adds information to the current list of PostScript fonts so that OzTEX can use the Lucida fonts available from Y&Y. Lucida is an alternative to Computer Modern, including math fonts, in Adobe Type 1 format.

Add MathTime Fonts — Adds information to the current list of PostScript fonts so that OzTEX can use the MathTime fonts available from The TEXplorators Corporation. MathTime is a set of math fonts suitable for use with Times Roman.

NOTE: Before using any of the above three config files you will need to change the path name that tells OzTEX where to find the font files that must be downloaded when printing to a PostScript device. These files are normally kept in the Fonts sub-folder of your System folder in System 7.1, or in the Extensions sub-folder in System 7.0. OzTEX doesn’t really care where you keep them, but it does need to be told where to find them.

These config files add information to the existing font list, so avoid selecting them more than once. If you decide to buy any of these fonts then the best thing to do would be to move the appropriate config file information into your Default file.

Some config files do not appear in the Config menu but can be loaded from the Configs folder:

Remove Help Menu — Removes OzTEX’s Help menu.

Old LaTeX — Configures OzTEX to typeset with the old L^{A}TEX 2.09 format; see section 5.1.

New LaTeX — Configures OzTEX to typeset with the new L^{A}TEX format; see section 5.1.

You can of course modify any of these config files to suit your own needs. If you’ve created your own config files and you think other people might find them useful, please e-mail them to me and I’ll add them to the standard OzTEX distribution.

4.6 The Help menu

The items appearing in this menu are read from the help list in a configuration file and must correspond to the names of text files in the Help-files folder. Selecting an item from the Help menu simply causes the contents of the corresponding file to appear in the OzTEX window.

Feel free to add more items to the Help menu. For example, you might like to create a file of TEX/L^{A}TEX commands to refer to while editing an input file. If you want to add more help files, or modify the existing ones, then there are a few things to watch out for. Don’t use tabs, and avoid long lines if you have a small screen. If you create a new help file then remember to update the Default configuration file.

5 L^{A}TEX

OzTEX is distributed with the latest implementation of L^{A}TEX (formerly called L^{A}TEX 2e). This new version of L^{A}TEX is described in the 2nd edition of L^{A}TEX: A Document Preparation System by Leslie Lamport and The L^{A}TEX Companion by Michel Goossens, Frank Mittelbach and Alexander Samarin. Both books are published by Addison-Wesley.

A number of important L^{A}TEX packages are provided. The psnfss package makes it easy to switch to PostScript text fonts instead of Computer Modern. The graphics package makes it easy to include Macintosh graphic files. See the documentation and test files in the PSNFSS and Graphics sub-folders in TeX-inputs. Other common packages are kept in the Tools sub-folder. More information about L^{A}TEX can be found in the .tex files in the LaTeX sub-folder.

The L^{A}TEX system included with OzTEX is not a full distribution (which is way too big for most OzTEX users). After installing the base files and the above packages, I deleted all the .dtx, .ins and .fdd files, as well as a few other files that were irrelevant for OzTEX users. If you need a file or package not provided in OzTEX, then you can ftp it from any CTAN site or mirror. The following table should help:

Sub-folder in TeX-inputs Corresponding CTAN directory

   LaTeX                    /tex-archive/macros/latex/unpacked
   Graphics                 /tex-archive/macros/latex/packages/graphics
   PSNFSS                   /tex-archive/macros/latex/packages/psnfss
   Tools                    /tex-archive/macros/latex/packages/tools

If you only need one or two files then ask me first and I might have a copy I can send by e-mail, but you must be a registered OzTEX user!

5.1 Using L^{A}TEX 2.09

The old L^{A}TEX 2.09 system is no longer distributed with OzTEX. L^{A}TEX users should seriously consider switching to the new L^{A}TEX; it can typeset L^{A}TEX 2.09 documents in “compatibility” mode. If you have the old L^{A}TEX system from an earlier version of OzTEX and you want to use it alongside the new L^{A}TEX, then carry out these steps:

1. Delete all log files for your existing L^{A}TEX documents so that OzTEX won’t get the wrong format by looking in a log file.

2. Edit the Default config file and insert "New LaTeX" and "Old LaTeX" anywhere in the list of config files.

3. Take the LaTeX sub-folder out of your old TeX-inputs folder, rename it Old LaTeX and put it next to (not inside) the new TeX-inputs folder. If you want to store the Old LaTeX folder somewhere else, or use a different name, then you’ll have to change the appropriate path in the Old LaTeX config file.

4. Build OldLaTeX.fmt (no space in the file name!):

(a) Start up OzTEX and select Old LaTeX from the Config menu.

(b) Run INITEX, type “lplain\dump” and hit Return.

(c) Save the format as OldLaTeX.fmt in the TeX-formats folder.

Before typesetting a L^{A}TEX 2.09 document you must remember to select Old LaTeX from the Config menu, and before typesetting a new L^{A}TEX document you must select New LaTeX.

6 Building format files

A format file contains a pre-compiled set of macros which TEX can load in very quickly. To build a format file you need to run INITEX (in the TEX menu). You may need to rebuild all format files if you edit a configuration file and change certain TEX parameters to suit your typesetting needs or your Mac’s memory capacity. Building a format file is quite easy; here are the steps used to create Plain.fmt:

1. Run INITEX, wait for the “**” prompt, type “Plain\dump” and hit the Return key. INITEX will begin reading plain.tex from the Plain sub-folder in TeX-inputs.

2. You’ll eventually get a standard dialog box allowing you to save the format information in the file and folder of your choice. The default file shown will be Plain.fmt. The best location for format files is the TeX-formats folder.

3. Note that Plain.log is created in the current folder. It’s not needed, so delete it.

The steps needed to create LaTeX.fmt are very similar:

1. Run INITEX, wait for the “**” prompt, type “LaTeX.ltx” and hit Return (you don’t need

     to add \dump). INITEX will read latex.ltx from the LaTeX sub-folder in TeX-inputs.

2. The dialog box will show LaTeX.fmt, so just save this file in the TeX-formats folder.

3. Delete LaTeX.log if you want to.

If you decide to rename one of the existing formats, or add a completely new format, then remember to update your configuration file(s).

6.1 Building big formats

Some people with very large or complicated documents will need to build big versions of the Plain or L^{A}TEX formats. Here’s how:

1. Read the comments at the top of the Big TeX configuration file. It sets most of the TEX parameters to very large values, but you may want to increase or reduce them depending on how much memory you have. It also sets the list of formats in the TEX menu to Big-L^{A}TEX and Big-Plain. You can change these to anything you like; just make sure your format names don’t contain any spaces.

2. After making any changes to Big TeX, click on the OzTEX icon and use “Get Info” in the Finder’s File menu to set OzTEX’s preferred memory size to a suitable value (use 3100K if you didn’t make any changes).

3. Restart OzTEX and select Big TeX from the Config menu.

4. Run INITEX and type in the appropriate string for the desired format: “Plain\dump” for Big-Plain or “LaTeX.ltx” for Big-L^{A}TEX.

5. When the dialog box appears, change the format file name to match the name listed in

     Big TeX (Big-Plain.fmt or Big-LaTeX.fmt) and save the file in the TeX-formats folder.

6. Delete the log files if you don’t want to keep them.

When you want to use a big format, select Big TeX from the Config menu first, then select the desired format from the TEX menu. If you’ll be using big formats all the time then you should copy the parameter settings from Big TeX into the Default configuration file and remove Big TeX from the config file list.

7 Fonts

OzTEX can use the following sources of font information in the process of typesetting, previewing and printing a document: TFM files, PK files, VF files, PostScript font files (for downloading non-resident fonts) and Macintosh screen fonts. The following sub-sections discuss all these font sources in some detail.

7.1 TFM files

A TEX Font Metric file contains the crucial typesetting information for a font, such as each character’s height, depth and width. The actual character images are not stored in a TFM file. TFM files are the only source of font information used when running TEX; it doesn’t need to know anything about character images to be able to create a DVI file. See The TEXbook if you want to know more about how TEX uses fonts, especially Chapter 4 and Appendix F.

OzTEX reads TFM files when printing or viewing a DVI file containing any of the fonts listed at the end of your configuration file. The dummy TFM file specified in your configuration file will also be read if a requested PK file can’t be found (PK files are discussed in section 7.3).

OzTEX will look for a TFM file in the current folder before looking in the sub-folders in TeX-fonts. All the TFM files in the CM sub-folder belong to the Computer Modern family of fonts (created by Donald Knuth using ). The TFM files in the LaTeX sub-folder are used by L^{A}TEX. The TFM files in the PS sub-folder correspond to PostScript fonts; their names follow a scheme devised by Karl Berry in an attempt to make TEX input files more portable. See section 7.4 for more information about these PostScript fonts.

7.2 Creating new TFM files

If the OzTEX distribution doesn’t provide a TFM file for a font you would like to use then there are a number of things you can do:

1. If you have access to the Internet then look for the TFM file in the nearest CTAN site (see the “Related Software” item in the Help menu). If the font is called foo then look for foo.tfm. If it is a PostScript font then you might have to search a bit harder; using Karl Berry’s scheme it might be called something like pfo.tfm. If you find it, remember that a TFM file must be transferred as a binary file.

2. If you can’t find foo.tfm then look for foo.mf. Such a file can be used by to create foo.tfm (and a corresponding set of PK files at any resolution you like). See section 13.

3. If foo is a PostScript font then look for foo.afm. An AFM (Adobe Font Metric) file contains very similar information to a TFM file. Alan Jeffrey’s fontinst package can convert an AFM file into a PL or VPL file which OzTools can then convert into a TFM file (see page 30).

4. As a last resort you could even create a PL file from scratch. A very tedious and error-prone job though.

Having found or created a new TFM file, you need to place it in a suitable folder so that OzTEX can find it. If you put it in one of the sub-folders in TeX-fonts (or create a new sub-folder) then you won’t need to change the TFM folder(s) in the Default config file.

If the TFM file is for a PostScript font then you must add a suitable entry to the list of fonts at the bottom of the Default config file. The examples in the file will show you what to do.

7.3 PK files

PK (packed pixel) files store the character images needed to print or view a DVI file containing fonts not listed at the end of your configuration file. For each such font there is usually a number of PK files, each one representing the same font but at a different size. This size (which has no relation to the font’s design size) is calculated as follows:

size = resolution × magnification

where resolution is either the printer resolution or the viewing resolution, and magnification is the overall font magnification (i.e., the DVI magnification times the individual font scaling). The size is then rounded up to the nearest integer and should equal (±1) one of the folder names in PK-files if you decide to keep PK files of the same size in separate folders.

Although TEX allows you to request a font at virtually any magnification, it is obviously impossible to provide an infinite number of PK files. The compromise solution is to provide a range of sizes for each font. These sizes are in a geometric ratio based on powers of 1.2 and correspond to TEX’s \magstep values. See Chapters 4 and 10 of The TEXbook for more details. For example, assuming a resolution of 300 and no document magnification:

TEX input  size  PK file

   \font\ra=cmr10  300 × 1.2^{0}  cmr10.300pk
   \font\rb=cmr10 scaled\magstephalf  300 × 1.2^{0.5} cmr10.329pk
   \font\rc=cmr10 scaled\magstep1  300 × 1.2^{1}  cmr10.360pk
   \font\rd=cmr10 scaled\magstep2  300 × 1.2^{2}  cmr10.432pk
   \font\re=cmr10 scaled\magstep3  300 × 1.2^{3}  cmr10.518pk
   \font\rf=cmr10 scaled\magstep4  300 × 1.2^{4}  cmr10.622pk
   \font\rg=cmr10 scaled\magstep5  300 × 1.2^{5}  cmr10.746pk

TEX’s \magnification command has a cumulative effect on font scaling:

   \magnification=\magstep1            % document magnification = 1.2
   \font\bigrm=cmr10 scaled\magstep2   % font magnification = 1.44

The font size is now 300 × 1.2 × 1.44 = 518.4, so OzTEX will use cmr10.518pk. Note that L^{A}TEX has no \magnification command — use the 11pt and 12pt options to increase the size of all fonts in a L^{A}TEX document.

For compatibility with other TEX systems, OzTEX uses a fairly complicated search scheme when looking for a font file. If foo is a PostScript font then OzTEX looks for foo.tfm in the current folder before looking in TeX-fonts. If foo is not a PostScript font then OzTEX looks for a PK file at the requested size. For example, if the calculated size is 300 then OzTEX will look for:

1. foo.300pk (in the current folder)

2. :PK-files:300:foo (relative to the location of OzTEX)

   3. :PK-files:300:foo.300pk  (ditto)
   4. :PK-files:foo.300pk  (ditto)

In fact, at each step OzTEX will also add and subtract 1 from 300 because rounding errors can occur in the size calculation. If still not found, OzTEX gives up and displays a warning.

There is still another possibility to consider: a font name can include an explicit location. For example, your TEX input file might contain \font\xxx=:myfonts:foo. In this case TEX will look for :myfonts:foo.tfm in the current folder; that is, it expects to find a file called foo.tfm in a sub-folder called myfonts. If not found then it gives up; it does not look for foo.tfm in TeX-fonts. Similarly, when you print or view the DVI file, OzTEX will only look for

:myfonts:foo.tfm if foo is a PostScript font, or for :myfonts:foo.300pk (or 301pk or 299pk)

if foo is a PK font. Note that the use of an explicit font location is not recommended as it decreases the portability of your TEX input file.

Most of the PK files supplied with OzTEX have been specifically generated for a 300 dpi, write-black laser printer (like the Apple LaserWriter). If your printer doesn’t have the same characteristics then you might need to get the correct PK files from some other source. Or build them yourself using as described in section 13.

Note that the 300 dpi PK files supplied with OzTEX can also be used on a 360 dpi printer like the StyleWriter (because 360 = 300 × 1.2). Two sub-folders, 394 and 896, complete the standard set of magnifications for a 360 dpi printer: 394 is the nearest integer to 360 × 1.2^{0.5} and 896 is the nearest integer to 360 × 1.2^{5}.

7.4 PostScript fonts

To be able to view or print a PostScript font in a TEX document, OzTEX needs to know certain information about the font, especially the name of its corresponding TFM file. This information is specified at the end of a configuration file (see the Default file).

The PostScript TFMs stored in the PS sub-folder in TeX-fonts are meant to be used in conjunction with the virtual font files stored in the VF-files folder (section 7.7 has more information about virtual fonts). These TFMs and VFs were created for the psnfss package by Sebastian Rahtz using Alan Jeffrey’s fontinst macros. The fonts are supplied in both OT1 and T1 encodings. The default encoding is OT1; this is the old TEX text font encoding described in The TEXbook. The T1 (or Cork) encoding is the new TEX text font encoding for 256-character fonts. The T1 TFMs and VFs have names ending in “q”. See test0.tex in the PSNFSS sub-folder in TeX-inputs for how to select either encoding.

Virtual PostScript fonts like ptmr should not appear in a config file’s list of PostScript fonts. Only the corresponding “raw” font (ptmr0) should be listed. Note that raw TFMs are indicated by names of the form *0.tfm. When OzTEX is fixing VFs it will replace characters from ptmrq.tfm with characters from ptmr0.tfm according to the mapping defined in ptmrq.vf.

Every PostScript printer has a certain set of resident fonts. To see an alphabetical list of the PostScript fonts available in your current printer, choose “Send PostScript … ” from the File menu, open the PS-files folder, and send the file getfonts.ps. The list should appear in the OzTEX window. If you’d prefer to print the list then send fontlist.ps.

The font you wish to use may not reside in the current printer, so OzTEX provides a mechanism for downloading non-resident PostScript fonts. For example, the following entry appears in the list of PostScript fonts at the bottom of the Default file:

   =   putr0   Utopia-Regular  <putr.pfa   Utopia   Mac.enc

The file to be downloaded appears immediately after the “<” character. When OzTEX translates a DVI file into PostScript, it checks if any fonts need to be downloaded. If putr0 is used on a selected page then the above entry tells OzTEX to include putr.pfa in the PostScript output. OzTEX looks for putr.pfa in the current folder first and then in the PS folder(s).

OzTEX can also download font information stored in a Macintosh-specific PostScript font file. It checks the type of the file specified after “<” and if the type is LWFN then it will download the PostScript code stored in the file’s POST resources. Such files are normally kept somewhere in your System folder (e.g., in the Fonts sub-folder under System 7.1), so you will need to add a suitable path to the PS folder(s) in the Default config file.

To print a DVI file that uses PostScript fonts on a non-PostScript printer you should have the corresponding screen fonts installed in your system. For example, if putr0 appears in the DVI file then OzTEX will try to use the screen font Utopia. If Utopia is not installed then OzTEX will display an error message and use the system font instead (normally Chicago). When previewing a DVI file, OzTEX will also warn you if it can’t find the screen font for a PostScript font; all characters from such a font will be shown using the system font in the missing font colour.

There are some important differences between PostScript fonts and the Computer Modern fonts created specifically for use with TEX:

1. A PostScript font can be requested at almost any size. For example, in Plain TEX you can

     do things like “\font\helv=phvr at 33.3pt”.

2. When a PostScript font is scaled to the same design size as a CM font it tends to look darker and larger. It is probably not a good idea to use the two font designs in the same document.

3. The standard TEX commands for accents and foreign letters need to be redefined for a PostScript text font. For Plain TEX users, the file pstext.tex in the Plain sub-folder in TeX-inputs contains the required macro definitions. Another file, psfonts.tex in TeX-docs, inputs these macros and illustrates the use (and abuse) of PostScript fonts in a Plain TEX document.

L^{A}TEX users can typeset a document with PostScript text fonts rather than Computer Modern by simply adding a suitable package declaration. For example,

   \documentclass{article}
   \usepackage{times}

will switch the default text font to Times-Roman. See the documentation in the PSNFSS subfolder in TeX-inputs for other possibilities. Note that CM math fonts will still be needed to typeset mathematics, but you can buy commercial font packages such as Lucida or MathTime that include PostScript replacements for these math fonts. Another alternative is to buy the CM/PS fonts from Blue Sky Research. These are PostScript versions of the Computer Modern fonts. OzTEX provides configuration files for switching to CM/PS, Lucida and MathTime.

7.5 Macintosh screen fonts

The fonts listed at the end of a configuration file are not restricted to PostScript fonts. The list is really for any non-PK font, and that could be an outline font in TrueType format, or even some sort of bitmap font in non-PK format. The critical requirement is that a matching TFM file exists so that TEX can typeset characters from that font.

When previewing a DVI file containing a non-PK font (or when printing such a file on a non-PostScript printer), OzTEX draws characters using the corresponding Macintosh screen font given in the config file. If the requested screen font can’t be found then OzTEX will warn you and use the system font instead. If you want to use PostScript fonts with OzTEX then for best results you should get the TrueType or ATM versions of the screen fonts listed in the Default config file.

7.6 Encoding files

Encoding files give you complete control over which Macintosh character is displayed when a particular PostScript character in a DVI file is to be viewed or printed on a non-PostScript printer (encoding files are not used during either low-level or standard PostScript printing).

Encoding files are loaded at the time a configuration file is loaded. Every PostScript screen font must be followed by an encoding entry which is either the name of an existing encoding file, or nil if the screen font uses the same encoding as its corresponding TFM file. OzTEX looks for a given encoding file in the current PS folder(s) and, if found, uses it to build an encoding array of 256 elements. This array defines the mapping of DVI character codes into Macintosh characters. You can see the currently loaded encoding arrays by selecting the appropriate sub-item in the Config menu’s “Show” item.

The syntax of an encoding file is described in detail in the standard encoding file called Mac.enc which is kept in the Encodings sub-folder in PS-files. This encoding file maps characters from a standard PostScript text font into equivalent characters in a standard Macintosh text font. Depending on the encoding scheme used in your PostScript TFMs or screen fonts, you might need to create other encoding files. For an interesting example of how such files can be used, see the View CM using PS configuration file.

7.7 Virtual fonts

Virtual fonts provide a convenient and flexible way to specify a mapping from TEX’s notion of a font character to the capabilities of a particular output device (e.g., screen or printer). In particular, virtual fonts make it easy to use PostScript fonts with TEX. The definitive document on virtual fonts is Donald Knuth’s article in TUGboat vol. 11 no. 1. A text version called knuth-vf can be found in the TeX-docs folder.

OzTEX supports virtual fonts via two items in the TEX menu: “Fix VFs in DVI” can be used to select a DVI file and replace all virtual font characters with appropriate characters from actual fonts (or with the specified rules and other DVI commands allowed in VF files). The code used to perform this task is based on Peter Breitenlohner’s DVIcopy program.

Another item, “Fix VFs after TEX”, can be ticked to tell OzTEX to automatically fix any VFs in the DVI file created at the end of a TEX run. This means you don’t have to remember to run “Fix VFs in DVI” before viewing or printing a DVI file that contains virtual fonts.

If you intend to make frequent use of virtual fonts then it would be a good idea to tick “Fix VFs after TEX”. Even if you only use virtual fonts rarely, it doesn’t hurt to tick this option. OzTEX can quickly check to see if any virtual fonts are used in a DVI file; if none are used then no further processing is carried out. To decide if font foo is virtual or not, OzTEX looks for a file called foo.vf in the VF-files folder.

If one or more virtual fonts are used then OzTEX reads the entire DVI file, creates a new DVI file with no virtual font references, deletes the original DVI file and renames the new file with the original name. If an error is detected, or if you decide to cancel processing, OzTEX will delete the new file and leave the original file untouched.

8 OzTools

OzTools is a companion program for OzTEX which includes the following TEX-related tools:

TFtoPL — Converts a TFM (TEX font metric) file into a PL (property list) file. The PL file will be created in the current folder; it is a human-readable version of the information stored in the TFM file. Apart from verifying the correctness of a TFM file, TFtoPL can also be used to modify the font metrics. For example, you can edit the PL file, change the amount of kerning between two characters, and run PLtoTF.

PLtoTF — Converts a PL file into a TFM file. The TFM file will be created in the current folder.

VFtoVP — Converts a VF (virtual font) file into a VPL (virtual property list) file. The VPL file will be created in the current folder; it is a human-readable version of the information stored in the VF file. VFtoVP also needs to read one or more TFM files from the folder path specified in the “Set TFM folder” dialog. (If you keep the OzTools application in the same folder as the TeX-fonts folder then you won’t need to change the supplied path. Note that multiple search folders are not supported, so it’s a good idea to keep all VF-related TFMs in the one folder. All of OzTEX’s VF-related TFMs are currently kept in the PS sub-folder in TeX-fonts.)

VPtoVF — Converts a VPL file into a VF file. The VF file will be created in the current folder. VPtoVF also creates a new TFM file in the folder specified by the “Set TFM folder” dialog.

OzTools provides some nice features for running these tools in a Mac environment. For example, the standard file dialog has a “Do all files” button which allows you to process all TFM/PL/VF/VPL files in the current folder. Background processing is supported. You can also delete PL/VPL files from within OzTools.

9 Transferring TFM/VF/PK/DVI files

OzTEX reads standard TFM/VF/PK files, and reads and writes standard DVI files. If you have access to TEX on some other computer system, you should be able to move such files to and fro without any further processing.

For the purposes of data transmission a TFM/VF/PK/DVI file must be treated as a binary file (a stream of arbitrary 8-bit bytes). When using Kermit to transfer binary files from another computer to your Mac, remember to type “set file type binary” before using the send command. The same goes for receiving such files from your Mac, but with one exception: to transfer a DVI file created by OzTEX to a VAX/VMS host you’ll need to type “set file type fixed” before using the receive command.

If you have access to the Internet then there is a huge library of TFM/VF/PK files available by anonymous ftp from many archive sites. When using ftp to transfer such files, remember to type the “binary” command before using “get”.

If you transfer a DVI file to your Mac and a mistake occurs during transmission, or if you forgot to send it as a binary file, then OzTEX will display some sort of error message soon after opening the file.

Note that a DVI file contains TFM file names; this can be a cause for concern if you plan to transfer DVI files from one TEX system to another system with a different set of TFM files. Another cause of portability problems are \special commands. If you have a choice, it’s always safer to transfer the original TEX input file so you can edit any incompatible font names or \special commands.

10 Including graphic files in TEX

Creating figures and illustrations with TEX isn’t easy. Although it is theoretically possible to place small dots anywhere on a page and build up an arbitrarily complex picture, time and memory limitations make such a scheme impractical. (L^{A}TEX provides a picture environment, but it is very inefficient and only suitable for small, simple diagrams.)

TEX does however provide a \special command which can be used to pass arbitrary information to the DVI interpreter. OzTEX’s printing and previewing code interprets a \special command using a simple syntax that allows inclusion of a given file.

Note that using \special can seriously reduce the portability of your TEX documents because a given DVI-reading program can only understand \special commands that obey its own particular syntax. One useful technique to enhance portability is to hide the actual \special call inside a macro; then when you move your TEX file to another computer all you need to do is change the macro definition (assuming the DVI driver supports similar functionality in its handling of \special). For an example of this approach see Larry Siebenmann’s boxedeps.doc and boxedeps.tex in the Plain sub-folder in TeX-inputs. Another alternative is epsf.tex; see epsftest.tex in the TeX-docs folder. Using either of these macro packages will make your input files much more portable.

A \special command can appear almost anywhere in your input file. It behaves like an invisible box of zero height and width. TEX simply stores the given information in the DVI file at the current page position. When previewing a DVI file, OzTEX draws a small marker indicating the location of a \special. The “Page Info” item will display this location in paper coordinates as well as the text of the \special command. Similar information is displayed if you choose to show statistics when printing a DVI file.

10.1 Including Macintosh graphic files

OzTEX allows the inclusion of three common types of Macintosh graphic files:

• PICT files can be generated by almost all drawing/painting programs on the Macintosh. A quick way to get a PICT file if you’re using System 7 is to type Shift-Command-3. To include a PICT file, use a command of the form:

     \special{pict=filename}

Note that OzTEX converts the PICT file into a black and white bitmap for previewing and printing, so you won’t see any colours. The bitmap is always at 72 dpi when previewing, but the current printer resolution is used when printing.

• PNTG files are also very common — they’re better known as MacPaint files. (Shift-Command-3 on a Mac running System 6 or earlier will create a screen dump in a file of type PNTG. If you have a colour monitor you’ll first need to set it to black and white.) To include a PNTG file, use a command of the form:

     \special{pntg=filename}

• EPSF files are becoming increasingly common. They contain encapsulated PostScript code in the data fork which OzTEX uses when PostScript printing and a corresponding PICT image in the resource fork which OzTEX uses when previewing or non-PostScript printing. To include an EPSF file, use a command of the form:

     \special{epsf=filename}

Keywords and file names are case-insensitive and spaces before the file name are ignored. For

example, \special{EPSF=FOO} is the same as \special{epsf= foo}.

To find a given \special file, OzTEX uses the same search strategy as that for a TEX input file. It looks in the current folder first, and then in the TEX input folder(s). The file name can also be a path name relative to the current folder, or a full path name. For example,

   \special{pict=:my-pict-files:foo}

will include a file called foo from a sub-folder called my-pict-files in the current folder. Spaces and other special characters (like =) can be included in a file name or path name by enclosing them in double quotes. For example,

   \special{pict="my pict file"}

will include a file called my pict file. Using spaces and other unusual characters in a file name is not recommended, particularly if TEX’s \input command might be used to read the file (as in the boxedeps.tex and epsf.tex macros). Also avoid using double quotes in a file name.

The PICT/PNTG/EPSF \special commands all allow you to preview graphics in your DVI file, but if you have a choice, use EPSF files because:

1. The output on a PostScript printer should be of much higher quality than a similar PICT/PNTG image.

2. A coloured EPSF picture will print correctly on a PostScript printer (assuming it supports colour) even though OzTEX will convert its PICT resource into a black and white bitmap when previewing.

3. The boxedeps.tex and epsf.tex macros can extract the bounding box information in an EPSF file and position the image automatically.

4. Encapsulated PostScript is supported on many other computers.

When creating a PICT/PNTG file it doesn’t really matter where you position the picture; OzTEX will convert it to a black and white bitmap, find the smallest bounding box of all black pixels in the bitmap, then place the bounding box so that its bottom left corner coincides with the location of the \special.

OzTEX does much the same thing for an EPSF picture; it places the lower left corner of the bounding box at the location of the \special. The only difference is that if the PICT 256 resource is being used (during preview or non-PostScript printing) then OzTEX makes no attempt to determine the smallest bounding box of all black pixels in the picture. This is because the picture’s dimensions should match those of the BoundingBox comment in the data fork (OzTEX will warn you if the dimensions differ by more than 3 bp).

OzTEX allows optional keyword=value pairs after the file name in a PICT/PNTG/EPSF \special. The keyword can also be terminated by a space. Here are the currently supported keywords:

• scale=n – scales a picture by a factor n (n must be > 0.0 and ≤ 100.0).

• hscale=n – sets the horizontal scale factor (and alters the aspect ratio).

• vscale=n – sets the vertical scale factor (and alters the aspect ratio).

• width=bp – sets the horizontal scale to get a picture at the desired width (bp is a number > 0.0 and ≤ 32000.0 in bp units, where 72 bp = 1 in). If no previous height keyword has been used then the vertical scale is set to the new horizontal scale to preserve the aspect ratio.

• height=bp – sets the vertical scale to get a picture at the desired height. If no previous width keyword has been used then the horizontal scale is set to the new vertical scale to preserve the aspect ratio.

If a particular keyword is used more than once in a single \special command then the last value is used. An illegal keyword or value will produce an error message when previewing or printing. Synonyms exist for most keywords:

   epsf  = eps or epsfile
   pict  = pictfile
   pntg  = macpaint
   hscale = xscale
   vscale = yscale
   width = wd
   height = ht

Here are some examples of how to use \special commands:

1. To include a picture at “normal” size:

     \special{pntg=ozicon}

2. To halve the size:

     \special{pntg=ozicon scale=0.5}

3. To double the width:

     \special{pntg=ozicon hscale=2}.

4. To set the height to 0.2 in and the width to 2 in:

     \special{pntg=ozicon ht=14.4 wd=144}.

5. To set the height to 0.5 in and preserve the aspect ratio:

     \special{pntg=ozicon ht=36}.

The figure on page 1 of this User Guide was created by using

   \special{pntg=folders scale=0.72}

to include an extract from a Macintosh screen dump. The scale value of 0.72 was chosen because it is a multiple of 0.24 = 72/300, where 72 dpi is the resolution of the MacPaint bitmap and 300 dpi is the resolution of my printer. This technique can improve the print quality of scaled bitmaps.

10.2 Compatibility with other DVI drivers

To provide better \special compatibility with dvips and other DVI drivers, OzTEX can process \special commands like

   \special{psfile=foo llx=100 lly=100 urx=172 ury=172 rwi=720 rhi=720}

where rhi is optional (it is used to change the aspect ratio). Note that llx and the other keywords shown above can only be used after psfile. Their order doesn’t matter. It is best not to type in such \special commands yourself; you should let epsf.tex or boxedeps.tex generate them.

The given file (foo in the above example) should normally be an EPSF file containing a BoundingBox comment. For compatibility with Wilfried Ricken’s DirectTEX, OzTEX also allows PICT files in a PSFILE \special. If foo is a file of type PICT then OzTEX will read in the picture stored in the data fork. If the given file name ends in “.pict” then OzTEX will get the picture from a PICT 256 resource (and if you put a suitable BoundingBox comment in the data fork then epsf.tex or boxedeps.tex can be used to position the image).

Note that if the given file does not contain a BoundingBox comment (PICT files cannot have such a comment) then you will need to supply the bounding box coordinates to epsf.tex; for example, \epsfbox[0 0 72 72]{foo}. The numbers must be given in bp units and in the following order: lower left x, lower left y, upper right x, upper right y.

10.3 Including PostScript files

OzTEX allows you to include a “raw” PostScript file using TEX’s \special command. However, if you have a choice then any of the methods described in the above sections are preferable because OzTEX cannot preview such a file, nor can it print the file on a non-PostScript printer.

Assuming you have a file called fig.ps that contains PostScript code for generating some sort of figure, the following command can be used to include this figure in a TEX or L^{A}TEX document:

   \special{fig.ps}

When printing the DVI file, OzTEX interprets the \special argument as a file name and then includes this file with the rest of the PostScript output. If it can’t find the file in the current folder then it looks in the PS folder(s). Don’t worry about removing any showpage command at the end of your PostScript file because OzTEX temporarily disables it.

It may take a little practice to position the figure correctly. The default PostScript origin is at the bottom left corner of the paper. However, when you include a file, OzTEX automatically moves the origin to the position of the \special. You can move the figure about by shifting the \special position, or by using a translate command in the PostScript file. The latter option is faster because you don’t have to run TEX again. Alternatively, you may prefer to place your figure at an absolute position on the paper. Simply use a command like initgraphics in the PostScript file. The position of the \special command then becomes irrelevant; just make sure it’s on the right page!

OzTEX also allows arbitrary PostScript code to appear after the file name. At least one space must be used to terminate the file name; further characters are included as a new line at the start of the given file. For example,

   \special{fig.ps 2 1 scale}

could be used to double the width of the figure. This feature allows you to include the same PostScript file more than once, but with a different starting line each time — useful if you need to produce the same diagram many times but with slight variations.

10.4 Rotating TEX material

OzTEX generates highly efficient PostScript code but it does so at the expense of some \special functionality. Most DVI-to-PostScript translators allow you to do things like use one \special to start rotating TEX text and another to stop the rotation. The way OzTEX interprets a DVI page makes this impossible. All the rules, fonts and \specials are collected in separate lists for later processing, so any sequential connection between these various page elements is lost.

However, assuming you have a PostScript printer, there is a way you can rotate arbitrary TEX material using OzTEX:

1. Create a TEX file that produces a single page containing only the material to be rotated (it’s a good idea to turn off page numbers by using \nopagenumbers in Plain TEX or

     \thispagestyle{empty} in L^{A}TEX).

2. TEX this file, select “Print DVI” and save the PostScript output in a file called, say,

     rotate.ps.

3. Edit rotate.ps and make these changes:

(a) If OzTEX used low-level PostScript to create rotate.ps then delete all lines from the top down to and including “1 @bop0”. If standard PostScript printing was used to create rotate.ps then delete all lines from the top down to and including the line ending with “ @setup” (note the space before the @).

(b) If low-level PostScript printing was used, replace the single line “1 @bop1” with these lines:

            0 0 transform         % get \special location in device coords
            mtrx setmatrix        % set TeX coords (units = dpi, res = 1in)
            itransform translate  % make \special location the new origin
            res 2 mul             % move right by 2in; adjust if necessary
            res -0.2 mul          % move up by 0.2in; adjust if necessary
            translate             % shift the origin
            -90 rotate            % 90 degrees anticlockwise

If standard PostScript printing was used, replace all lines from “end % OzTeXdict” to “1 @bop1” with the above lines.

(c) If you want the output to appear in a fixed position on the page (regardless of the location of the \special command) then remove the lines containing “0 0 transform”

         and “itransform translate” (but keep the “mtrx setmatrix” line).

(d) Delete all lines from the bottom of the file up to and including “1 @eop”.

4. Include \special{rotate.ps} in the TEX file in which you want the rotated material to appear. Leave an appropriate amount of vertical space before the \special.

5. Run TEX and print the DVI file. Either low-level or standard PostScript printing will work at this stage. If you need to shift the location of the rotated material then adjust the translate parameters in rotate.ps (note that you don’t need to run TEX again).

The TeX-docs folder contains two files, rotate.tex and table.tex, which illustrate how this works.

The above method is not very practical if you have a lot of material that needs to be rotated. In such a situation you should consider using a macro package that generates \special commands targeted for dvips; see section 14.

11 Recovering from errors

OzTEX reports errors by displaying a message in the OzTEX window or in a dialog box near the top right corner of the screen. In the latter case there are two types of error dialogs:

1. Warning messages appear in a box with a single Continue button.

2. Fatal messages appear in a box with a Quit button (which will quit OzTEX).

Most errors, particularly the serious ones, are accompanied by a beep. Let’s now look at the most likely errors you’ll encounter and what you can do to prevent them recurring.

11.1 Errors when loading a configuration file

If an error occurs while loading in a configuration file then OzTEX will display a suitable message in the OzTEX window. The error message will also include the line number in the file, although this can be misleading if you do something like forget an “=” character. It is advisable to switch to your editor, fix the error and reload the configuration file before attempting to do anything else, particularly if the error is in the Default file. See section 2.2 for a precise description of the syntax required in a configuration file.

11.2 Errors when loading an encoding file

These errors can occur when OzTEX is loading a configuration file that contains a list of PostScript fonts. If OzTEX complains that it can’t find an encoding file then check the PS folder(s) parameter in the configuration file. The encoding files supplied with OzTEX are all stored in the Encodings sub-folder in PS-files. OzTEX does not look in the current folder for an encoding file.

Various syntax errors are possible when reading an encoding file. The resulting message should provide you with enough information to fix the problem. See the comments at the start of Mac.enc for a detailed description of the legal syntax.

11.3 Errors when running TEX

Nearly all the errors you’ll see when running TEX will be the result of mistakes in your input file. The TEXbook is the best place to look for solutions, especially Chapters 6 and 27. Lamport’s L^{A}TEX manual also has a section devoted to errors. The following errors are more likely to occur due to OzTEX’s particular implementation of TEX.

Can’t find file

There are a number of likely reasons why TEX can’t find a file:

1. The file does not exist in either the current folder or in any of the sub-folders within TeX-inputs. If TEX was looking for a format file then make sure it is in the TeX-formats folder.

2. You could have spelt the file name incorrectly.

3. The file name might contain an illegal character. A Macintosh file name can contain just about any character, but TEX is not so flexible. Don’t use spaces and avoid non-alphabetic characters in all file names that might be seen by TEX.

If you see such an error then the best thing to do is hit Command-C or Command-Dot to abort TEX and either rename the file or move it to the correct folder.

Not enough memory

The most likely time you could run out of memory is when using INITEX to create a format file. INITEX typically requires more memory than TEX — just how much more depends on the TEX parameters in your configuration file. If you do run out of memory then quit OzTEX, select the OzTEX application icon, choose “Get Info” from the Finder’s File menu, and increase the preferred size.

Fatal format error

You probably changed one of the critical TEX parameters in your configuration file and forgot to rebuild the format. Run INITEX and rebuild the offending format file (see page 24).

TEX capacity exceeded

Such an error message will be accompanied by additional text describing which parameter has been exceeded. Before doing anything else, first check for some common errors. If the exceeded parameter is stack_size then make sure you haven’t defined an infinitely recursive macro. If the exceeded parameter is buffer_size then it is quite likely that the lines in your input file are too long; possible causes include using an editor that automatically wraps lines without inserting end-of-line characters, or incorrectly transferring a text file from another computer (like a PC) that uses a different end-of-line character.

Look at the list of TEX parameters in your configuration file and check if the exceeded parameter appears there; if it is listed then you might be able to solve the problem by simply increasing the parameter’s value and reloading the configuration file. Note that if you change the value of mem_top, hash_size, hash_prime or hyf_size then you will also need to rebuild all format files (see page 24).

11.4 Errors when viewing a DVI file

Missing fonts

During interpretation of a DVI page you may get a warning message if OzTEX can’t find a PK file, or if a PostScript font’s matching screen font is not installed. Such warnings will only appear once for each missing font (but not at all if the “Ignore missing fonts” check box was selected). The “Page Info” item indicates all missing fonts. Note that can be used to build a missing PK file; see section 13.

Virtual fonts

If OzTEX detects a virtual font (like ptmr), it will display a warning message reminding you to run “Fix VFs in DVI”.

Page off paper

If OzTEX detects that any part of a DVI page is off the paper then it will beep and show a full view. TEX will often catch these errors (e.g., overfull \hbox or \vbox) but there are quite a few situations where it can’t. TEX really has no idea about what paper size you intend to print its pages on.

If you’re sure the problem isn’t in your input file then use the “Page Info” item to see what OzTEX thinks the paper dimensions are. You could have forgotten to reset the landscape option or you might have made a mistake when changing the paper dimensions in a configuration file.

\special errors

When interpreting a DVI page OzTEX will check any \special commands and warn you about the following problems:

• An unknown keyword.

• A file that can’t be opened.

• A file type that does not match the first keyword (PICT/PNTG/EPSF).

• A bad value after an optional keyword.

No warnings appear if the “Ignore bad \specials” check box was selected.

11.5 Errors when printing a DVI file

OzTEX detects basically the same set of errors whether it is viewing or printing a DVI file. In the latter case the error messages appear in the OzTEX window along with a beep. If you’ve been sensible and previewed the DVI file before printing it then you should have discovered nearly all the errors (and fixed them).

To avoid wasting paper you should always view a DVI file before printing it and choose “Page Info” to check for any missing fonts (but don’t worry about missing screen fonts if you have a PostScript printer). Another way to check for errors is to send PostScript output to a file instead of the printer, although this won’t detect certain errors that can only occur with a non-PostScript printer.

Printer errors

While sending output to any type of printer you might get status messages indicating a problem such as an empty paper tray or a paper jam. Once you’ve fixed the problem printing can normally continue.

Can’t open \special file

OzTEX expects the argument of a \special command to contain a file name. It won’t be able to open the file if you spelt its name incorrectly or if the file isn’t in the correct folder.

Bad \special command

If OzTEX detects any sort of error in a \special command then a suitable message will be displayed in the OzTEX window. Note that you will get an error message if you try to print a DVI file that includes a “raw” PostScript file on a non-PostScript printer. See section 10 for the \special syntax and semantics supported by OzTEX.

PostScript errors

You shouldn’t see any errors in the PostScript code generated by OzTEX, but there may well be problems in a PostScript file included by \special. (You can always tell which is the culprit by commenting out the \special command.) If you are sending the output to a printer rather than spooling software then any PostScript error should cause a message to appear in the OzTEX window. Any further output will be flushed and printing cancelled.

So what can you do? For starters, get the PostScript Language Reference Manual by Adobe Systems. Debugging a PostScript program can be a frustrating experience. Try downloading the error handler stored in errhandler.ps. If the problem isn’t obvious then use print and flush commands to isolate just where the error is occurring. The Ghostscript program mentioned in “Related Software” can also be useful.

Non-PostScript scaling errors

Before OzTEX starts non-PostScript printing, it checks to see that the printer resolution parameter matches the actual resolution of your printer. If the resolutions don’t match then OzTEX will warn you that scaling problems may occur. This warning appears just before the print dialog in case you want to Cancel printing (you might have forgotten to switch to the correct configuration file).

If you decide to go ahead and print the DVI file, you might see problems such as horizontal gaps at regular intervals down each page. OzTEX prints a page by sending a sequence of horizontal bands to the printer. The number of bands depends on how much memory is available (the band height is displayed when showing statistics). Scaling problems can result in gaps or overlapping at band boundaries, but they can be avoided by bumping up OzTEX’s memory to a suitably large value so that only one large band is needed to print each page.

12 Changing OzTEX’s resources

This section is for people who know how to use a resource editor like ResEdit. The following resources in the OzTEX application can easily be changed:

• STR 200 and 201 specify the location and name of the default configuration file.

• STR 300, 301, etc. specify the keyboard short cuts used when previewing (see page 10). All the resources are named, so it is easy to see which string corresponds to which short cut. OzTEX uses the first character in each string. Note that you might need to open a string resource with the hex editor if you want to insert a non-displayable character like Delete or Return.

• The various MENU resources can all be modified. You might like to change the name of a menu item or add a new Command key equivalent. Just be careful not to change the number or order of items in any menu.

13 OzTEX and Metafont

All the dialog boxes used to print or view a DVI file have a check box called “Make missing PK fonts” (only available in System 7 or later). The state of the check box is remembered when OzTEX quits. If “Make missing PK fonts” is checked and OzTEX detects a missing PK font when printing or previewing a DVI file, then will be called to build the required PK file.

OzTEX does not call directly. Instead it starts up MakeTeXPK, another of Tom’s programs. The very first time this happens, OzTEX will ask you to find and select the MakeTeXPK application. The selected application is remembered for future use.

MakeTeXPK calls to build a GF (Generic Font) file, then it calls GFtoPK to convert the GF file into a PK file. OzTEX uses the new PK file to continue previewing or printing. Note that the PK file is created in the PK-files folder. You can either keep the PK file there or move it into an appropriate sub-folder. A PK file called foo.999pk should be stored in a sub-folder called 999. If no such sub-folder exists then create one.

It is possible that the font creation process will fail. For example, might not find the required .mf input file. Or you might decide to cancel the process. In such cases OzTEX will report a missing PK font and append a line of information to a file called missfont.log in the PK-files folder.

If “Make missing PK fonts” is not checked then OzTEX won’t attempt to create a missing PK font, but it will append a line to missfont.log. The missfont.log file can be used later by MakeTeXPK to build all the listed PK fonts. For many people this might be more convenient than having OzTEX build PK fonts on the fly — it can take quite a while for to create a font.

Unless you have a Power Mac (and Tom’s native PPC version of ), I recommend leaving “Make missing PK fonts” unchecked, at least initially. Preview all your DVI files and select “Page Info” from the View menu. If there are any missing PK fonts, OzTEX will create a missfont.log file. Edit this file and remove any duplicate lines. Start up MakeTeXPK, open missfont.log, select Run and go to bed! When you wake up, all the PK files should have been created in the PK-files folder.

It is a good idea to delete (or rename) missfont.log after using it to build PK files. OzTEX simply appends missing font info to missfont.log without checking to see if that info already exists, and MakeTeXPK simply builds all the listed PK files, even if they already exist. (Tom and I might do something smarter one day, although it is quite easy to remove duplicate lines from missfont.log with a good text editor.)

If you preview a DVI file and select the “Ignore missing fonts” check box then the “Make missing PK fonts” setting is ignored. If a missing PK font is detected then OzTEX won’t attempt to call MakeTeXPK, nor will it append any information to missfont.log. This feature is useful when previewing certain DVI files (like trip.dvi) where you know there are missing fonts but you have no desire to create them.

13.1 Setting the Metafont mode

To be able to build a PK file, needs to know what mode to use. OzTEX gets this information from a configuration file: the printer and viewing resolutions each have an extra string parameter that is simply passed on to .

WARNING: The given strings must exactly match known mode_def values defined in the file modes.mf which is kept in the mfinputs sub-folder of the Metafont folder. It is also important to make sure that a given resolution value matches the pixels_per_inch value in the corresponding mode_def, otherwise won’t create a suitable PK file.

The Default config file sets both modes to laserwriter. You might need to change these modes, either by selecting one of the supplied config files (StyleWriter, ImageWriter or Linotronic), or by editing the Default config file. If a mode string is empty ("") then will use the localfont mode which is currently equivalent to the laserwriter mode.

   Common modes for OzTEX users are laserwriter, stylewriter, imagewriter and linohi.

If none of these modes suit your particular printer then look in modes.mf to see if there is a suitable definition. The most important thing to look for is a pixels_per_inch value that matches the resolution of your printer. If you can’t find a matching mode_def (unlikely), you will have to create your own and run inimf to build a new mf.base file. See Readme.mf in the Metafont folder for details.

NOTE: I’ve set the stylewriter mode_def parameters in modes.mf to be the the same as the laserwriter parameters (except for pixels_per_inch of course). This was done so that both modes can share the same set of PK files. People who are fussy about their pixels (or with better eyesight than me) might want to optimize the stylewriter parameters for that printer.

14 OzTEX and Dvips

Tom Rokicki’s dvips is the most widely used DVI-to-PostScript driver. It provides a number of sophisticated features that are not available in OzTEX’s DVI-to-PostScript code. The OzTEX distribution includes Tom Kiffe’s implementation of dvips, and OzTEX can call it if you are using System 7 or later.

To call dvips, just tick the “Use DVIPS” flag in the File menu and then select either of the top two items in the same menu. These items will have changed from “Print DVI … ” and “Print foo.dvi” to “DVIPS … ” and “DVIPS foo.dvi”. After opening the DVI file, OzTEX displays a dialog like this:

This dialog is very similar to the one used for low-level PostScript printing (see page 11). Here are the changes:

• The “Conserve VM” check box is replaced by “Compress PK fonts”.

• There is no “Save PostScript file” button. In its place is an edit box for entering extra dvips options (dvips has a lot of options; see dvips.txt in the Dvips folder).

• There is no “Page increment” edit box. Add “-A” to the extra options box to select odd TEX pages, or “-B” to select even TEX pages.

When you click on the DVIPS button, OzTEX will display the selected options and call dvips. The very first time this is done, OzTEX will ask you to find and select the dvips application. The selected application is remembered for future use.

Soon after starting up, dvips loads the config.ps file (stored in the ps sub-folder of the Dvips folder). This sets up various default parameters including the resolution and mode for making missing PK fonts. The config.ps file currently contains suitable parameters for an Apple LaserWriter at 300 dpi. You might want to edit config.ps if you have a different printer. See the dvips manual for more details; the source for this Plain TEX document is the dvips.tex file in the Dvips folder.

If you have access to more than one type of PostScript printer then set up config.ps for the most commonly used printer. To select parameters for a different printer, enter “-P xxx” in the extra dvips options box. This tells dvips to load config.xxx after config.ps. Of course, you will need to create a file called config.xxx. The config.linohi file defines suitable parameters for a Linotronic typesetter, so to select output for this printer you would enter “-P linohi”.

Note that dvips will only call to build a missing PK font if the “Make missing PK fonts” box was checked. If not checked, then dvips (like OzTEX) will append a line of information to missfont.log in the PK-files folder.

Given foo.dvi as input, dvips will create an output file called foo.ps. (Add “-o filename” to the extra options box to create a different file.) When dvips finishes processing you can use the Transfer menu to start up Tom’s PrintPS program and print foo.ps. PrintPS does much the same job as OzTEX’s “Send PostScript … ” item. PrintPS also has a handy item that automatically deletes the file after sending it to the printer.

14.1 Why use Dvips?

There are some good reasons why you might want to use dvips rather than OzTEX’s DVI-to-PostScript translator:

• The dvips program runs on many different computer systems.

• The PostScript code generated by dvips is more portable and conforms to Adobe’s document structuring conventions. This allows other programs like psnup and psselect (available in Tom’s full CMacTEX distribution) to manipulate the dvips output in many interesting ways.

• dvips provides better support for sophisticated graphic operations like rotation and colour changing. In particular, dvips fully supports the L^{A}TEX graphics package, including commands like \rotatebox and \colorbox which OzTEX’s DVI translator does not support.

Note that dvips does not support the OzTEX-specific \special commands for including PICT and PNTG files. Likewise, OzTEX does not support many of the dvips-specific \special commands. Before previewing a DVI file with lots of \special commands targeted at dvips, it is a good idea to turn on the “Ignore bad \specials” check box.

One way to ensure \special compatibility between OzTEX and dvips is to restrict yourself to the inclusion of EPSF files using the macros in boxedeps.tex or epsf.tex. For an example of the latter, see epsftest.tex in the TeX-docs folder. After TEXing this file (using the Plain format), not only will OzTEX be able to preview the DVI file, but both OzTEX and dvips will produce identical output on a PostScript printer. (OzTEX can also produce the same output on a non-PostScript printer.)

WARNING: Do not create DVI file names containing “*”, “~” or “/”. OzTEX doesn’t care, but dvips has a Unix heritage and these characters have special meanings which will prevent dvips reading the file. For these and other reasons, it is good policy to restrict yourself to letters and digits when naming TEX (and thus DVI) files. If you really need some sort of separating character then “-” is a safe choice.

15 More information

Many TEX-related books are available through TUG, the TEX Users Group. They also produce an excellent magazine called TUGboat. Anybody planning to use TEX a lot is strongly advised to join. The “TEX Users Group” item in the Help menu explains how to get in touch.

If you have access to the Internet then another good source of help and information about TEX-related topics is the comp.text.tex newsgroup.